Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support


Apple IIGS
#46:    DrawPicture Data Format

Written by:    Jeff Erickson & Keith Rollin                     November 1988

This Technical Note describes the internal format of the QuickDraw II picture 
data structure.
_____________________________________________________________________________

This Technical Note presents the internal format of the QuickDraw II picture 
data structure for informational purposes only.  You should not use this 
information to write your own bottleneck procedures; the only routines which 
should create and read PICT format files are those provided in QuickDraw II.  
If we added new objects to the picture definition, your program would not 
operate on new pictures.  This Note documents this information for debugging 
purposes only.


Picture Data Structure Definition

Pictures are stored in memory in the following format:

They begin with a WORD which indicates the mode of the port which was used to 
record when the picture was created.  This information is useful when the 
picture is played back, possibly in a different graphics mode.

Following the WORD is a RECT which indicates the frame of the picture and is 
used for scaling when you redraw the picture.  Following the RECT is the 
version number of this PICT format, then a series of word-sized opcodes which 
describe the sequences of QuickDraw II commands that were used to create the 
picture.

Name        Description                         Size (bytes)
pictSCB     picture's scan line control byte    2 (high byte = 0)
picFrame    picture's boundary rectangle        8
version     picture version                     2 (Currently $8211)
opcode      operation code                      2
<data>      operation data                      variable, depending on opcode
:
opcode      operation code                      2
<data>      operation data                      variable, depending on opcode


Opcodes

As mentioned above, pictures are described by a series of opcodes which are 
used to record the QuickDraw II commands that created the picture.  These 
opcodes are two bytes long and are usually followed by a number of parameters.

All currently defined opcodes and their parameters are listed below.  Any 
opcodes not listed here are reserved.

Opcode Name          Description         Parm Bytes    Parameter Description
$0000  NOP           no operation        0             none
$0001  ClipRgn       clip to a region    [region size] region
$0002  BkPat         background pattern  32            background pattern (8x8 
                                                       pixels)
$0003  TxFont        text font           4             Font Manager font ID
                                                       (long)
$0004  TxFace        text face           2             text face (word)
$0005  TxMode        text mode           2             text mode (word)
$0006  SpExtra       space extra         4             space extra (fixed)
$0007  PnSize        pen size            4             pen size (point)
$0008  PnMode        pen mode            2             pen mode (word)
$0009  PnPat         pen pattern         32            pen pattern (8x8 pixels)
$000A  FillPat       fill pattern        32            fill pattern (8x8
                                                       pixels)
$000B  OvSize        oval size           4             oval size (point)
$000C  Origin        origin              4             origin (point)
$000D  TxSize        text size           2             text size (word)
$000E  FGColor       foreground color    2             color (word)
$000F  BGColor       background color    2             color (word)
$XX11  Version       version             0             none: high byte=version 
                                                       (currently $82)
$0012  ChExtra       character extra     4             char. extra (fixed)
$0013  PnMask        pen mask            8             mask (8 bytes)
$0014  ArcRot        arc rot             2             Reserved (related to
                                                       things drawn with
                                                       patterns). (word)
$0015  FontFlags     font flags          2             font flags (word)
$0020  Line          line                8             pnLoc (point), newPt
                                                       (point)
$0021  LineFrom      line from pen loc.  4             newPt (point)
$0022  ShortLine     short line          6             pnLoc (point), dv, dh 
                                                       (signed bytes)
$0023  ShortLFrom    ditto from pen loc  2             dv, dh (signed bytes)
$0028  LongText      long text           5+text        txLoc (point), count
                                                       (byte), text
$0029  DHText        hor. offset text    2+text        dh (unsigned byte),
                                                       count (byte), text
$002A  DVText        vert. offset text   2+text        dv (unsigned byte),
                                                       count (byte), text
$002B  DHDVText      offset text         3+text        dv, dh (unsigned bytes), 
                                                       count (byte), text
$002C  RealLongText  very long text      6+text        txLoc (point), count
                                                       (word), text

Opcodes between $0030 and $008C are a combination of a graphic verb and a 
graphic object, as listed below (where "V" stands for the graphic verb, and 
"X" is a stands for the graphic object).  For example, $0069 means 
PaintSameArc, and is followed by two one-word parameters.

Graphic Verbs:

$00X0      Frame...      frame something            [Specific to object type
                                                    see below.]
$00X1      Paint...      paint something
$00X2      Erase...      erase something
$00X3      Invert...     invert something
$00X4      Fill...       fill something
$00XV+8    ...Same...    draw same thing somehow    [See below; {braced}
                                                    parms do not appear.]

Graphic Objects:

$003V      ...Rect       draw a rectangle somehow   8 (0 if - SameRect) {rect
                                                    (2 points)}
$004V      ...RRect      draw a round rect somehow  8 (0) {rect (2 points)}
$005V      ...Oval       draw an oval somehow       8 (0) {rect (2 points)}
$006V      ...Arc        draw an arc somehow        12 (4) {rect (2 points)},
                                                    start, arc angle (words)
$007V      ...Poly       draw a polygon somehow     [polygon size] (0){polygon}
$008V      ...Rgn        draw a region somehow      [region size] (0) {region}
$0090      BitsRect      copybits, rect clipped     variable* (see below, but
                                                    without maskRgn)
$0091      BitsRgn       copybits, rgn clipped      variable* (see below)
$00A1      LongComment   long comment               4+data kind (word), size
                                                    (word), data

*Bits... data:

origSCB       original scan line control byte  2               SCB (word --
                                                               high byte = 0)
BWvsColor     black and white vs. color        2               reserved (word)
width         width of pixel image in bytes    2               width (word)
boundsRect    bounds rectangle                 8               rect (2 points)
srcRect       source rectangle                 8               rect (2 points)
destRect      destination rectangle            8               rect (2 points)
mode          transfer mode                    2               pen mode (word)
maskRgn       mask region (BitsRgn ONLY!)      [region size]   region
pixData       pixel image                      [pixdata size]  width*
                                                               (bounds.bottom-
                                                               bounds.top)


Differences Between IIGS Pictures and Macintosh Pictures

1.    QuickDraw II pictures are modeled after PICT2 on the Macintosh, 
      which use two bytes for its opcodes and data (the exception to 
      this is the $11 (version) opcode, which is followed by a one-byte 
      parameter).  Macintosh PICT 1.0 formats, which use one-byte 
      opcodes, would have to undergo extensive modifications to be 
      displayed on the IIGS.
2.    There is no EndOfPicture opcode on the IIGS as there is on the 
      Macintosh.  Also, the first word of the picture is a pictSCB, not 
      the length of the picture.  The picture size is determined solely 
      by the size of the handle on the IIGS.  There is also no picture 
      header on the IIGS as on the Macintosh.
3.    The number sex of the Macintosh is opposite that of the Apple 
      IIGS. The Macintosh stores the high bytes of words and long words 
      first, whereas the IIGS stores the low byte first. 
4.    The following Macintosh picture opcodes are not available on the 
      IIGS: txRatio, PackBitsRect, PackBitsRgn, shortComment, 
      EndOfPicture.
5.    QuickDraw II defines the following opcodes that the Macintosh does 
      not: ChExtra ($12), PnMask ($13), ArcRot ($14), FontFlags ($15), 
      and RealLongText ($2C).


Notes on the Interpretation of IIGS Pictures

o    The state of the pen, the clip region, various patterns and 
     colors, and the origin of the current port is saved before a 
     picture is drawn, and restored afterwards.  The current port is 
     set up in a default state equivalent to that of a newly created 
     port just before drawing begins.  Picture opcodes act just like 
     their QuickDraw II tool counterparts, with a few exceptions.
o    Two pen locations are tracked as the picture is drawn, one for 
     lines and one for text.  Thus, LineFrom always draws from the end 
     of the last line, regardless of any intermediate text opcodes.
o    Text calls do not change the position of the "text pen," as do 
     normal QuickDraw II text calls.  Thus, if a picture contains two 
     lines of text, the second one directly below the first, the second 
     will be stored using a DVtext opcode.
o    DrawPicture performs considerable setup before it draws pictures.  
     Among other things, it calls InstallFont, which is a Font Manager 
     call.  If you are going to support pictures in your application, 
     you should load and start the Font Manager. 


Further Reference
o    Apple IIGS Toolbox Reference, Volume 2

